BTHome component docs #5640
Open
BTHome component docs #5640
+216
−0
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This adds comprehensive documentation for the new BTHome v2 BLE component that enables ESP32 devices to broadcast sensor data using the BTHome protocol. The documentation covers: - Complete configuration options including sensors, binary sensors, and encryption - All supported sensor types (temperature, humidity, battery, etc.) - All supported binary sensor types (motion, door, window, etc.) - Detailed examples showing basic and advanced usage - Integration with Home Assistant - Explanation of immediate advertising for event-driven sensors Related to esphome/esphome#11962
- Replace docref shortcodes with standard markdown links - Add full domain to external Home Assistant Bluetooth link - Replace apiref shortcode with direct API reference link
15 tasks
✅ Deploy Preview for esphome ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Copilot finished reviewing on behalf of
jesserockz
November 18, 2025 09:39
Contributor
There was a problem hiding this comment.
Pull Request Overview
This PR adds documentation for the new BTHome v2 BLE component that enables ESP32 devices to broadcast sensor data using the BTHome protocol.
Key changes:
- New component documentation explaining configuration, supported sensors, and integration with Home Assistant
- Added BTHome BLE entry to the Bluetooth/BLE components index
Reviewed Changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| content/components/bthome.md | New documentation for BTHome v2 BLE component with configuration options, sensor types, examples, and integration details |
| content/components/_index.md | Added BTHome BLE entry to the Bluetooth/BLE components index |
|
|
||
| - **min_interval** (*Optional*, [Time](/guides/configuration-types#time)): The minimum BLE advertising interval in milliseconds. Setting this less than `max_interval` gives the BLE hardware a better chance to avoid collisions with other BLE transmissions. Range: 20ms to 10,240ms. Defaults to `1s`. | ||
|
|
||
| - **max_interval** (*Optional*, [Time](/guides/configuration-types#time)): The maximum BLE advertising interval in milliseconds. Setting this greater than `min_interval` gives the BLE hardware a better chance to avoid collisions with other BLE transmissions. Range: 20ms to 10,240ms. Defaults to `1s`. |
There was a problem hiding this comment.
The description states "advertising interval in milliseconds" but the range and default values are specified using time units (e.g., "1s"). The description should be "The maximum BLE advertising interval" without mentioning "in milliseconds" since the configuration type is Time which supports various time units.
Suggested change
| - **max_interval** (*Optional*, [Time](/guides/configuration-types#time)): The maximum BLE advertising interval in milliseconds. Setting this greater than `min_interval` gives the BLE hardware a better chance to avoid collisions with other BLE transmissions. Range: 20ms to 10,240ms. Defaults to `1s`. | |
| - **max_interval** (*Optional*, [Time](/guides/configuration-types#time)): The maximum BLE advertising interval. Setting this greater than `min_interval` gives the BLE hardware a better chance to avoid collisions with other BLE transmissions. Range: 20ms to 10,240ms. Defaults to `1s`. |
| - **id** (*Optional*, [ID](/guides/configuration-types#id)): Manually specify the ID for code generation. | ||
| - **esp32_ble_id** (*Optional*, [ID](/guides/configuration-types#id)): The ID of the [ESP32 BLE](/components/esp32_ble) component. Defaults to the only `esp32_ble` component if only one is configured. | ||
|
|
||
| - **min_interval** (*Optional*, [Time](/guides/configuration-types#time)): The minimum BLE advertising interval in milliseconds. Setting this less than `max_interval` gives the BLE hardware a better chance to avoid collisions with other BLE transmissions. Range: 20ms to 10,240ms. Defaults to `1s`. |
There was a problem hiding this comment.
The description states "advertising interval in milliseconds" but the range and default values are specified using time units (e.g., "1s"). The description should be "The minimum BLE advertising interval" without mentioning "in milliseconds" since the configuration type is Time which supports various time units.
Suggested change
| - **min_interval** (*Optional*, [Time](/guides/configuration-types#time)): The minimum BLE advertising interval in milliseconds. Setting this less than `max_interval` gives the BLE hardware a better chance to avoid collisions with other BLE transmissions. Range: 20ms to 10,240ms. Defaults to `1s`. | |
| - **min_interval** (*Optional*, [Time](/guides/configuration-types#time)): The minimum BLE advertising interval. Setting this less than `max_interval` gives the BLE hardware a better chance to avoid collisions with other BLE transmissions. Range: 20ms to 10,240ms. Defaults to `1s`. |
jesserockz
changed the title
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Description:
This adds comprehensive documentation for the new BTHome v2 BLE component that enables ESP32 devices to broadcast sensor data using the BTHome protocol.
The documentation covers:
Related issue (if applicable): fixes
Pull request in esphome with YAML changes (if applicable):
Checklist:
I am merging into
nextbecause this is new documentation that has a matching pull-request in esphome as linked above.or
I am merging into
currentbecause this is a fix, change and/or adjustment in the current documentation and is not for a new component or feature.Link added in
/components/index.rstwhen creating new documents for new components or cookbook.New Component Images
If you are adding a new component to ESPHome, you can automatically generate a standardized black and white component name image for the documentation.
To generate a component image:
Comment on this pull request with the following command, replacing
COMPONENT_NAMEwith your component name in UPPER_CASE format with underscores (e.g.,BME280,SHT3X,DALLAS_TEMP):The ESPHome bot will respond with a downloadable ZIP file containing the SVG image.
Extract the SVG file and place it in the
images/folder of this repository.Use the image in your component's index table entry in
/components/index.rst.Example: For a component called "DHT22 Temperature Sensor", use: